Export API¶
Overview¶
Ticket information is sent over HTTP with POST name/value pairs as the ticket information. The data is sent via POST to a URL provided by you, along with a username/password to send with the ticket data. The names of the available POST data is given in [Table1]. 2 POST name/value pairs are given in addition to the ticket data, named “username” and “password”. This is used to authenticate with the external ticketing system, and combined with HTTPS it can provide a secure channel for communication. When a ticket export was successful, the response body is expected to contain the id for the ticket on the external ticketing system (if applicable), and an id for the individual issue/note created, encoded in XML.
Work flow¶
When an agent handles a support request, they first find the subscriber in the ticketing system. The agent then selects the service the subscriber is having a problem with. They are then presented with a list of available issues, which could either be generic issues provided by serverplus or a list of issues provided by the company being supported. When the issue is selected a decision tree is available for the technician to follow which provides problem resolution steps.
At the end of the call, the technician can either mark that subscriber’s issue as resolved, pending, open or escalated. Internally, the ticketing system will associate like service problems with each other, called a Ticket. If a user calls once about problems with their dialup service, and the problem is unresolved and escalated if they call back again about their dialup service the issue will be associated to the same ticket until it is resolved.
Data Description¶
The available data is as follows:
| Name | Description | |||
|---|---|---|---|---|
| subscriber_id | Unique id for the subscriber who’s ticket information is being exported. This is provided by the billing hooks implemented by the company being supported. If there are no billing hooks in place for this company, the value will be an empty string. | |||
| subscriber_name | Name of the subscriber | |||
| subscriber_email | Email address for the subscriber, unknown is blank string | |||
| subscriber_phone | Phone for subscriber - this may contain text. Unknown is blank string. | |||
| time | The time the support issue started, in mountain standard time. The format is a string such as ‘YYYY-MM-DD HH:MM:SS -/+HHMM’. The last 5 characters represent the time zone’s offset from UTC. An example time would be: ‘2009-01-21 13:51:22 -0700’ where the MST offset is -7 hours | |||
| time_utc | The time the support issue started, in UTC time. The format is a string such as: ‘YYY-MM-DD HH:MM:SS’ An example time would be (the same time as above, but in UTC): ‘2009-01-21 20:51:22’ |
|||
| status | a text representation of the ticket’s status. Available options are ‘resolved’, ‘pending’, ‘open’, ‘escalated’. ‘pending’ is an unresolved issue waiting on the subscriber, ‘open’ is an unresolved issue waiting on support, ‘escalated’ is an unresolved issue waiting on the service provider. | |||
| notes | The notes a technician has entered about the support call. Can contain Unicode characters, new line characters, single and double quotes. Data should be filtered and escaped where necessary. | |||
| service | a text description of the service the support call was about | |||
| issue | a text description of the issue the support call was about | |||
| issue_id | A unique id for the issue the support call was about. This is only applicable when custom issues are being used for the company being supported, otherwise it is a blank string. | |||
| dt | text representing the decision tree. This is in a format with the question first, and the answer following with the delimiter being a newline character. Additional questions are separated by a newline character. An example, with ‘\n’ being a newline is : “Question 1\nAnswer 1\nQuestion 2\nAnswer 2” The questions/answers are presented in the order they were asked/answered. |
|||
| dt_json | Decision Tree information encoded in JSON. This is an array of Question/Answer pairs. A Question/Answer pair is an array of 2 strings, where the first string is the question and the second is the answer. The first question would be dt_json[0][0], and the first answer would be dt_json[0][1]. If there are no questions the initial array would be zero length. This contains the same information as the item above , but encoded in a easy to use format. | |||
| escalation_info | If a support request was escalated, this will contain any service-specific information collected during the escalation process. The data that is required to be filled out can vary by service, and is normally only modified upon request. This consists of both the name of the required information, and the value collected by the technician. The format is the same as decision tree information. An example is: “Callback Number\n555-5555\nAddress\n123 North Briar Ave. “ The order of the name/value pairs is not guaranteed to be consistent, so an escalation for the same service with the same required information could be returned as: “Address\n123 North Briar Ave.\nCallback Number\n555-5555 “ If data is being extracted form this information, it should be done by the name of the required information rather than its position. |
|||
| escalation_info_json | Escalation information encoded in JSON. The format is the same as dt_json, where escalation information is stored in an array of name/value pairs. The name of the first escalation information would be escalation_info_json[0][0], and the value for that would be escalation_info_json[0][1]. When no escalation information is provided, this is an empty array. | |||
| staff | Name of the staff member that created the support ticket | |||
| text_representation | A text representation of the ticket. This combines the staff name, status, service and issue name, decision tree , escalation info and notes into one string containing newline and tab characters. The format for this is not guaranteed to be consistent and is intended to be used when exported ticket information will only be inserted into another ticket systems notes field. | |||
| incident_id | A unique identifier of the support request for this service and issue in IssueTracker. This can be considered the unique id for the notes exported. | |||
| ticket_id | A unique identifier of the support ticket in IssueTracker that this issue is being associated to. | |||
| ticket_external_id | A unique identifier of the support ticket on the external ticketing system, if one was returned on previous exports for the same ticket. | |||
| company_id | A unique identifier for the company which the subscriber belongs to. This is the same as the company_id provided for the subscriber_detail look up on the billing hook search. This is blank when one has not been provided during the setup process. | |||
Expected response codes¶
When a HTTP call is generated, there are 3 expected HTTP response/status codes from the external ticketing system:
| Code | Result |
| 200 OK | The ticket export was successful. The response body is parsed to find the ticket id in the external ticketing system (ticket_external_id) |
| 400 Bad Request | The export was not successful and should not be queued for later delivery. This can be due to incorrect/incomplete information inside of the ticket (i.e. a subscriber_id that does not exist in your customer database) |
| 401 Unauthorized | The provided username/password is not valid. The external ticketing system is working properly, it just needs valid credentials to POST tickets and the ticket POST did not save on the external ticketing system. The ticket will be queued for another attempt later. |
| All Others | There was an unknown error. The external ticketing system may not be working properly. The ticket may not have been saved and will be queued for another attempt later. |
Expected response body¶
Upon a successful ticket POST the response body must contain an XML document named “response”, with 2 child elements named “incident_id” and “ticket_id”. The values for these should be as follows:
| ticket_id | The unique identifier for the ticket on the external ticketing system. This can be up to 60 characters in length, and can be blank. If given, any new issues associated to this same ticket will use this value for the ticket_external_id field when exported. |
| incident_id | The unique identifier for this particular issue/note on the external ticketing system. This can be the same as the incident_id given during the export, and can be blank. This may be used in future versions of the API to allow an external ticketing system to POST tickets to IssueTracker, and allow IssueTracker to check for duplicate tickets. A blank value for this field means the information was received successfully, but was not added to the external system. This may be necessary in cases where only tickets of a particular status, such as escalated, are being stored. |
An example response body would be:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<ticket_id></ticket_id>
<incident_id>77236</incident_id>
</response>
This valid response doesn’t return a ticket_id, but does return an incident_id. If the XML is not formed properly, or the incident_id is not given the response will be assumed to be an invalid and attempted later.
Testing¶
A tool is available to send test ticket exports via IssueTracker to your URL. This can be found via the “Dev” menu, under “Ticket Exporting”. It can also be found at the URL:
http://tracker.serverplus.com/tickethooks
The test tool lets you input the URL, username, and password to test, along with test ticket information such as ticket_id, subscriber_id, and notes. The decision tree and escalation information as sent statically as 2 data pairs. When the export receiver is working properly, the URL, username and password should be sent to it@serverplus.com to have tickets sent automatically.